Welcome

Welcome to Horodruin Help

Intro

Long, long ago, to start from the beginning, I'm looking for a file synchronizer that can handle more that just 2 folders but more confortable than the included system "briefcases".
It have to:

  • be small, clean, simple and powerful.
  • run on every workstation (unlike some replication services...).
  • handle 2 or more folders at the same time.

Since I have never found anything similar so I began to think about writing one by myself.
After having rewritten it twice (the file-comparing engine was really a mess), here there is the result of my efforts. I still have to add some more feature, but it seems to be quite reliable (I use it daily at work).

Actually it has the following key features:

  • multiple folder handling (2 or more).
  • the folder analysis can be modified to fit your needs.
  • multithreaded.
  • optimal multithreaded file copy engine (by using temporary file and/or by overwriting files).
  • configurable. You can easily integrate it with a text editor, a hex editor, and a diff viewer.
  • minimal registry usage (only for Explorer integration).
  • small, fast, and clean.
  • HTML Help included.

The program is engineered to be simple but not idiot-proof. It's addressed to users with a quite strong technical background. So if you are a beginner, probably this program is not for you.

A bad usage of the program could lead to the loss of your data. So when you use it, you have to be careful and you have to know exactly what you are doing.

I hope you find it useful as I do.

Best regards

Stefano Bordoni


Horodruin - Quick Start

Quick Start

The folders you have to synchronize are called sources, and you have to define at least two.
Each folder is located by its local full path name ('C:\blah\blahblah'), or its full UNC path name ('\\MyPC\blahblahblah').

After you have defined them, you can start to analize them. The results' report is shown into the main window.

Then it's time to do the dirty work and the program will do it for you.
In this way you can synchronize several folders just by a couple of clicks.

Remember that whereever you are, you can press F1 to get the help.

Adding the 'sources'

Select the proper toolbar button, the menu Sources->Add.

adding a new source

You can simply add it from the right-click menu or by clicking on the toolbar (or you may drop a folder from the Explorer).

A dialog containing all available source's options will appear.
Here input the path field. Leave the other params to the defaults, and then click OK.

Repeat the operation for each folder you have to handle.

Analyzing

After having set up all needed sources, you have to analyze their contents to fill them with files stats data.
So click on Sources->Analyze, or press F5.

click it from the toolbar...

Note that each source has its own access rights that can be edited, and its current status.

The program will start to collect data about sources' contents. A small window will show you the operation progress.
When the task is completed, a brief report is displayed for each filled source.

From here you can have an idea of what is going on. For example, into the above report, no source is updated.

If you see an unknown icon, you can press F1 to see the description.

Synchronizing

Now click on Sources->Synchronize, or press F6 and the program will do the dirty work.

Finally a dialog appears with the report of occurred errors (if any).
Congratulations. You have completed the task.


Horodruin - Sources

Sources

Intro

A source is one of the folders you need to synchronize.
Actually it may any valid local folder (like "c:\") or UNC folder (like "\\server1\shared\").

You can add one or by clicking Sources->Add from menu or from the toolbar, or by dropping folders directly from Explorer.
If you drag a file, the program gets its folder as a source. If a folder is already included into a source, it's ignored.

Property Dialog

When you insert a new folder or edit an existing one the following dialog will pop up.

source property dialog

When you press OK button, the program tries to verify the given folder. It must not be included into another source.

Source Path The folder you need to synchronize.
Actually you can only use local or (UNC) remote folders.
To fill it, you can type the value in it, or simply by using the Browse button.
Sometimes it's possible that, you can't locate a network folder by browsing it. Try to explore it, and when you have found it, you can paste the proper path into its dialog field.
Explore | If you wish to peek into the folder, just click the Explore button and and explorer window will pop up (only if the folder exist).
File/Folder Masks
This filters the files and/or the folders you want to care.
"*.txt" will care every file with .txt extension, while "*.txt;a*.*" will care the previous ones and every file with its name starting by 'a'.

The first row is the mask of the files you want to care about, the second is the mask to exclude files taken by the previous one.

Note that the source will not handle the "not included" and excluded files at all (i.e. the source will ignore them even if they are present elsewhere).

If you double-click, click '...' button, or press F2, an input helper will pop up (the window to the right).

In this dialog you can easily edit the Masks items (one item per row).

Flags
Allow item Creating Allow item Reading Allow item Writing | These flags handles what the analysis process can assume or not. These will be very handy in all cases you wish a read only folder, or an update-only folder and so on.
Use Binaries' Version Infos | Enable binaries' Version Infos handling. This will improve binaries file comparison but it affect the analysis speed.
Use NULL Version Infos | By checking this, the comparison cares about version infos even if they aren't present in both items. More details are explained here.
Max Folder Level | This is the maximum folder level you need to recurse.
Use temp. Files This rules on temporary file usage during the synchronization process.

Actually you have 3 options:

  • The first one is not using them at all. It's quicker and it takes less storage space, but if the folder has a problem and the copy is not complete, you will loose the original file.
  • The second is using them always. It is slower and it takes more storage space, but it is safer indeed. This because if any trouble occurs, your original file is preserved until the copy of the newer is complete.
  • The third option is to specify an upper limit to use them. This should be a good compromise between files' integrity and the available storage space.
    The temporary files will be used for the smaller ones only.
    You can express this limit in bytes, in kilobytes (by adding a 'k'), in megabytes ('m'), in gigabytes ('g').
Use Bin. Ver. Infos This enable/disable the file version handling. Using it will improve binaries file comparison but it affect the analysis speed.
Remember, a file without version infos is considered always older than a file with these infos. So, if you are in need to disable it in one source, it's better to do it in all other sources too.

Note: whenever you change source's options, you will loose all its collected data and you will have to analyze sources' contents again.

Handling the Sources

After having setup all the needed sources, there are things we can do with them.

The first one is the order them from the quickest (usually local folders) from the slowest.
Although the program should catalog the source type, the order may have some effect on choosing file newest candidate (if there are many copies of it).
The source order is recorded into the program data files.

If a source doesn't need to be updated very frequently (a slow device, a removable disk, a mobile PC), it can be disabled.
Disabled sources are simply ignored (no analysis, no synchronization).
This status is recorded into the program data files.

If we need to synchronize the source, we have to analyze them.
After this task, the source is filled with source's contents stats data.
Once filled a source will not be analyzed again. To force it, we can invalidate source data.
This allows to do something like to load and analyze all the enabled sources, enabling a disabled one and analyze it too (without processing the filled ones anymore).

Finally if we need to see and alter the source result, we can always use the Source Result Viewer window.


Horodruin - How It Works

How It Works

The program takes the data from 2 o more sources and then process them to build a virtual updated folder.
A source is a folder to synchronize. It can be a local o remote path (UNC).

To create the virtual updated folder, the program merges the sources, it compares their items and then it shows results.
There are just a couple of points to keep in mind about:

  • the file comparison.
    Version informations
    If both files have version infos, then they are used in the following way:

    Product Version is more important than File Version.
    If they are equal, the Build Type is taken to try to determine the newest candidate.
    The program recognizes the following build types (more...less important): patched, released, prereleased, debug.
    If the 2 versions infos are matching, the program tries to use the time-stamps.

    If one file doesn't have version infos, and its source has NULL version infos handling enabled then the versioned file is considered earlier.

    Last updated time-stamps
    If no version data are available into the files, then the last updated time-stamps are taken to determine the newest candidate.

    To workaround to a NTFS bug, two timestamps are equal if their difference is less than 2 seconds.
    This is the common approach for this kind of program.
    File sizes
    If they seem to be equal a test on their size is made.

    If they are equal, no problem. The files seems really equal.
    If they aren't, then the greater is considered newer then the other.

  • the files' access rights.
    They can be used to limit the analysis and the actions on these files. If a file cannot be read, it cannot be taken as the newest candidate.

These comparisons will determine the newest candidate, i.e. the file that will be taken to update all other sources.

As you can see, the results are shown in a quite new way. This is dued by the task that the program has to handle. Comparing more than 2 folders excludes the common usage of the two file panels.
If you want to see the results details, you have to use the Source Results Viewer.

Once you issue a synchronization the program tries to apply the needed changes to clone the updated items into each sources. These changes include the updated timestamp and file attributes.

Again if you need a more selective approach for one of your sources, you should alter its access rights.
Using them you can define if:

  • it can be read (i.e. an have a 'newest' candidates or not).
  • it can write over the existing files (or delete them).
  • it can create the missing ones.

Finally you can go on to synchornize files only if you have 2 or more filled sources (see Icons).


Horodruin - Settings

Settings

From the Main window File menu you can access to the preferences window.

source property dialog

Version Files This is the list of the file types used to look for version informations.
Version infos is a widely used way to mark executable files under win32 environment. Use it as much you can.

You can add a new entry by pressing INSERT key.
You can edit an entry by selecting it and pressing F2 key.
You can delete an entry by selecting it and pressing DELETE key.
External Tools Horodruin can handle several external tools.

An external text viewer (windows notepad is set up by default).
An external hex viewer (if you haven't one, give a look to frhed).
An external difference viewer (if you haven't one, give a look to WinMerge).

Here you have to locate the main program file (double click the field if you don't remember its localtion), and extra parameters if any.


Horodruin - Source Result Viewer

Source Results' Viewer

This window displays the sources results, and it's divided in 3 main panels.

The Navigation Panel (the blue one) contains some handful tools (see below).
The main panel is the Results' Tree Panel (the red one). Here are displayed the source's comparison results.
The Comparison Panel (the green one) shows the file data across the filled sources.

Navigation Panel

From here you can:

  • change the current source.
  • see the source stats.
  • filter the (treeview) results by their states.

Results' Tree Panel

This panel contains the results of the file analysis. Every file has access rights & status icons.

At the top of the treeview, there is the current selected item. This item is the one shown into the Comparison Panel.
You can go from here to this panel and viceversa by pressing SPACE key.

You can select multiple items, and navigating through them by using CTRL+UP/DOWN keys. Note that you can select only visible items filtered from Navigation Panel.

Once you have selected something, you can apply one of the supported operations.

Actually you can:

  • force the newest file candidate selection.
  • mark/unmark for the deletion (the same item through all filled sources) during the synchronization.
    There are few things to be aware of:
    • the file will be deleted and not placed into the Recycle Bin, so be careful.
    • you need 'write' permissions to delete an item.
    • if you mark a folder, all its analyzed items are marked too (visible or not).
      Note that all analyzed items may not be all contained items, so the folder might not be deletable anyway.
  • mark/unmark updated item(s), to forced them to be overwritten.
  • change item(s) access rights (this might change item newest candidate selection).
  • restoring the 'original' newest candidate selection.

Overwrite mark, and forced candidate selections are lost if you invalidate the source data.
Delete mark, is mantained as long as there is at least one 'valid' source containg the marked items.

Comparison Panel

This panel shows the details of the current selected Result Tree item across each filled source.
They are sorted by the newest (top) to the oldest (bottom).
Version infos are shown only if they are available.

From here you can mainly do the same things, you can from the Result Tree, but you can also:

Set Newest Candidate | Choose which file to use for the copy, i.e. the one copied into all other sources. You can do it also by double clicking it. Note that by default newer & updated files are not overwritten. If you need to overwrite them, you have to mark them.
Mark to be Overwritten | An 'updated' file will be overwritten with the selected item.
Mark for Deletion | The item will be deleted.
Handling Flags | Edit item's Handling flags
Explore Source | A file explorer is opened into the folder containing the selected file.
Open File | To open the file with the default associated program.
Send To | To send the file to one of the external program (see Settings).


Horodruin - Open Issues

Open Issues

It follows a small list of known open issues.

0305061 - Source Validation

It may happen that the program fails to validate a source.

With v1.0.68.0 this should happen only when you share an empty volume in a network (for example: "\\myPC\CDWRITER").

The problem occurs because the program validate the source folder in 2 steps:

  • validate by file system into cataloguing API ("FindFileFirst"...). Unluckly these APIs do not work fine with network shares.
  • if the first test fails and the source folder is a network UNC folder, then the program tries to peek into it. If it finds something (mainly '.' or '..' folders) then it is valid.

Well I think that there are at least 2 walkarounds. The first is simply copy something into this disk (the 2nd test doesn't fail anymore), the second is mapping the network shares as a drive.

From v1.0.70.1 this problem should be fixed.
The taken approach is to peek into the source to get the first item. In case of failure (source is empty) it looks for system error codes to see if there is no file or it's a bad path.


Horodruin - Closed Issues

Closed Issues

It follows a small list of known open issues.

0305061 - Source Validation

It may happen that the program fails to validate a source.

With v1.0.68.0 this should happen only when you share an empty volume in a network (for example: "\\myPC\CDWRITER").

The problem occurs because the program validate the source folder in 2 steps:

  • validate by file system into cataloguing API ("FindFileFirst"...). Unluckly these APIs do not work fine with network shares.
  • if the first test fails and the source folder is a network UNC folder, then the program tries to peek into it. If it finds something (mainly '.' or '..' folders) then it is valid.

Well I think that there are at least 2 walkarounds. The first is simply copy something into this disk (the 2nd test doesn't fail anymore), the second is mapping the network shares as a drive.

From v1.0.70.1 this problem should be fixed.
The taken approach is to peek into the source to get the first item. In case of failure (source is empty) it looks for system error codes to see if there is no file or it's a bad path.

0307301 - 'Read Only' Attribute Troubles

A friend of mine, has reported to me several "access denied" during the update of the 'last updated' time-stamp at the end of synchronizations.

After a short investigation we have discovered that it was caused by the copy engine operation sequence.
It was trying to set source file attributes and then to restore the timestamp.

This is a problem, with a file with read-only attribute on.
It leaves the file updated but with a wrong time-stamp. A very annoying behaviour from the next synchronization, because it may overwrite a newer file with a good time-stamp.

The things are lightly better when using the temp file on a target with read only attribute. At the end of the synchronization, the target isn't updated at all.
This is caused because the engine fails to delete the original old file before renaming the temp one.

From the v1.0.73.1 this problem should be fixed.
The approach taken now is slightly changed.

Now when temp files are used, the attributes are resetted, and then the original old file is deleted.
When they aren't used, the time-stamp is updated and then the attributes are set.

Changing the attributes doesn't touch file's 'last updated' time-stamp.

0307302 - The Program Doesn't Even Start

When the program is started, an error pops up, and it states that one of the following DLL is missing:

borlndmm.dll
cc3260mt.dll
rtl60.bpl
vcl60.bpl

The problem here seems that you haven't one of the needed VCL6 Runtimes Libraries.
The most common case is that you have skipped the setup screen that advice you may have needed them.
Install the VCL 6 Runtime Libraries, and the program should now run fine.

You can download them from the program site (see contacts).

030818 - Missing Synch Results

Somewhen it occurs that some synchronization errors aren't collected into results window. Into my own case it happens that I try to write a single file on a closed CDR, and sometimes the synchronization went fine.

In a first time I think about some sort of bug into the copy engine, but I have discovered that it was a strange race condition.
I have discovered that sometimes the output thread could generate an error before the calling class (and the results collecting engine) overcasts the virtual entry point (method).
In this case, the virtual method is still the base (empty) one.

From the v1.1.81.0 this problem should be fixed.
Now the output threads now wait for the calling class has been fully initialized before doing anything else.

030926 - Analysis Over Network Sources is Quite Slow

The default behaviour during a source analysis, is to count all its file in a first time, and analyzing them in a second time.
This approach works fine with the local devices because most of the file system data used is cached by the system the first time.

With network sources this is not true, the first step data aren't cached and the second step has to asking them again.
This has 2 major drawbacks. The first one is that the network traffic is doubled, while the other is that the second step lasts exactly like the first one.

I have noted it during a 14000-15000 items' analysis. The speed doubles when I disable the first step (from 125 to 61 seconds).
The file count is guessed by keeping the greater source item count already processed. The only drawback I have found is that starting the analysis with a network source produces a not-so-fine effect on the progressbar and the stats label. Really a small price for such enhancement.

From the v1.1.88.0 this problem should be seriously reduced.

Probably this will not be the final approach the program will take to face the problem, but actually we will see what will need of a further improovment.


Horodruin - Command Line

Command Line

The program can be started from the command line and supports the following syntax:

horodruin.exe -<command> <command params>

actually the following commands are supported:
open | open the following data file. The file may be specified by using " too (they are needed if it contains one or more spaces). For example: horodruin.exe -open "d:\temp\sample.hrd"
analyze | open & analyze the following data file. The file may be specified by using " too (they are needed if it contains one or more spaces). For example: horodruin.exe -analyze "d:\temp\sample.hrd"


Horodruin - Contacts

Contacts

Program Home Page:
http://stefanobordoni.interfree.it/Stefano/loading.htm?Horodruin

You can contact me by writing to my personal account.

If you have found a bug, use the program bug report feature (see 'Help' menu).
This will instruct you in how to do it correctly.


Horodruin - File Handling Flags

File Handling Flags

Once analyzed the sources, it is possible to modify the way the selected item (file or folder) is handled during the synchronization by updating its access rights.

They have the same effects of sources' ones.

In this dialog it is possible to set flags, or apply a boolean mask (AND, OR, XOR).


Welcome

This is the first time you start the program.

Before starting to use it, I suggest to you to give a read to this document because it can give you the right idea about the program.
How it is structured, how it works, what you can expect from it ...and so on.

This page will not popup anymore, but if you need this help just press F1 key, or select the proper command into menu.

Let's start.


Horodruin - Icons

Icons

Access Rights

Every object in this program has its own access rights.

The object can be read, so it may be used to update all the others.
The object can be created, so it can be updated where it doesn't exist too.
The object can be overwritten, so it can be updated where it already exists.

Sources States

The source is operative and ready to be analized/filled.
Pressing SPACE or double-clicking it, will open Source Properties window.
The source is analized, filled and ready to be synchronized.
Pressing SPACE or double-clicking it, will open Source Results Viewer window.
The source is updated. This may occur even immediately after the analysis.
The number of updated files may not be equal in all updated sources (generally by their options).
Pressing SPACE or double-clicking it, will invalidate it.
The source is disabled by the user. It will not be analized and/or synchronized.
This may be useful when a source needs to be synchronized rarely (slow computer/device/network).
The program can work without it if there are at least 2 other valid sources.
This status is saved into the program's files.
Pressing SPACE or double-clicking it, will enable it.
The source is invalidated usually because its UNC folder path isn't available anymore (it's deleted, a disk/storage is removed, ...) or there is a problem on folder system access rights.
This state is something between the disabled and the ready status.
The program can work without it if there are at least 2 other valid sources.
If it's an unexpected event, I suggest to track it down, and repeat the analysis.
Pressing SPACE or double-clicking it, will open source's properties window.

File States

After analyzing the sources, each file has it own state that shows what it program will do during the synchronization.

The file will be created.
The file will be deleted (see Source's Results Viewer).
The file is disabled and so it will be ignored.
The file will be overwritten (i.e. you will loose its original contents).
If you are not really sure of what you are doing, it should be better to avoid this situation.
This file is the selected one. It will be taken to update all the others.
This file is already updated (i.e. it is equal to the selected one).
This file is already updated but you want to overwrite it anyway (see Source's Result Viewer).